CD Ware Multimedia 1995 May

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / TOOLS / DF_DEBUG.ZIP / DFDDOC.ARC / DFD.DOC

Wrap

Text File | 1988-09-14 | 133.5 KB | 4,061 lines

DFD ┌────┐ │ GS │ └────┘ Data File Debugger Version 1.10, May, 1987 Version 1.20, September, 1988 (C)Copyright Gilmore Systems - 1986,1987,1988 All rights reserved Gilmore Systems P.O. Box 3831 Beverly Hills, CA 90212-0831 Voice: (213) 275-8006 Data: (213) 276-5263 First Printing: December, 1986 Second Printing: September, 1988 Programs and documentation written by: Charles B. Gilmore Gilmore Systems (C)Copyright Gilmore Systems - 1986, 1988 All rights reserved No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Gilmore Systems. The above paragraph is waived for ver 1.20 when used for evaluation purposes only. Disclaimer Gilmore Systems makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Gilmore Systems reserves the right to revise this publication and to make changes from time to time in the content hereof without obligation of Gilmore Systems to notify any such person of such revision or changes. Under no circumstances will Gilmore Systems or the author be held responsible for any consequential or inconsequential damages resulting from the use of any furnished programs or documentation. C86 is a trademark of Computer Innovations. IBM is a trademark of International Business Machines, Inc. Microsoft and Microsoft Pascal are trademarks of Microsoft Corp. Turbo Pascal is a trademark of Borland International. Turbo C is a trademark of Borland International. Table of Contents Page 1 TABLE OF CONTENTS Table of Contents .................................................... 1 DFD Overview ....................................................... 1-1 What is DFD? ................................................. 1-2 What You Need ................................................. 1-3 Getting Started ............................................... 1-4 Data Dictionaries .................................................. 2-1 Turbo Pascal .................................................. 2-2 Turbo Pascal - Comments ....................................... 2-6 Turbo Pascal - DAD "Tags" ..................................... 2-7 Turbo Pascal - Creating the DAD ............................... 2-9 Microsoft Pascal ............................................. 2-12 Microsoft Pascal - Additional Features ....................... 2-13 Borland's Turbo C, MS C and Computer Innovations C86 ("C") ... 2-14 Turbo C, MS C and Computer Innovations C86 ("C") - Comments .. 2-19 Turbo C, MS C and Computer Innovations C86 ("C") - DAD "Tags" 2-20 Turbo C, MS C and C86 ("C") - Creating the DAD ............... 2-22 The Data File Debugger (DFD) Program - Using DFD ................... 3-1 Starting DFD .................................................. 3-2 Top Half of the DFD Display Screen ............................ 3-3 Bottom Half of DFD Display Screen ............................. 3-5 Bottom Half of DFD Display Screen - "Rec:" prompt ............. 3-6 Bottom Half of DFD Display Screen - "Subsc" prompt ............ 3-8 Bottom Half of DFD Display Screen - "D A T A" prompt .......... 3-9 The Data File Debugger (DFD) Program - Advanced Section ............ 4-1 Dimensioned Variables ("Subsc" Prompt Field) .................. 4-2 Zapping (batch entry) ......................................... 4-3 Assignment Oriented Language (AOL) ............................ 4-4 Converting Data to Other Languages ............................ 4-6 DAD Utility Programs ............................................... 5-1 DADSORT ....................................................... 5-2 DAD2SRCE ...................................................... 5-3 DADRPT ........................................................ 5-5 DADUNIQ ....................................................... 5-6 DFD Demo - Walking Through the Demo ................................ A-1 Index .............................................................. B-1 DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Overview Page 1-1 What is DFD? What is Data File Debugger? Data File Debugger (DFD) is a unique and powerful data file and database debugging tool. Most all application programs, whether their written in C, Pascal, or any other language write their data to random files which have been described by a record layout. In Pascal, this record layout is described by the RECORD statement and usually consists of nested records and CASEs. In C, the record layout is described by the STRUCT statement, and usually consists of nested structs and UNIONs. Likewise, in BASIC, records are described by the FIELD statement, and in COBOL they're described by a 01 level record in the Data Division. Although Pascal is Pascal, and C is C, the way different Pascal and C compilers generate code to store data into files varies from compiler to compiler. For instance, Microsoft Pascal uses IEEE standard for real numbers, whereas Borland's Turbo Pascal uses their own way of storing real numbers. Microsoft Pascal aligns data items on word boundaries, whereas Turbo Pascal does not. So if you were to compile the same Pascal program under Microsft and Turbo Pascal, you'd find they wouldn't be able to read each other's data. The same goes for different C compilers. Computer Innovations C86 compiler stores it's data without aligning it on word boundaries, whereas Turbo C offers the option of aligning data on word boundaries. Microsoft C defaults to word boundary alignment with the option of byte (packed) alignment. DFD supports Computer Innovations C86, Microsoft Pascal, Borland's Turbo Pascal, Borland's Turbo C, and Microsoft C. Support for other languages will be developed if demand is high enough. DFD allows you to interactively display, dump, modify, zap, and fill data elements in the data file or database by the same variable names that describe the record layout in your source code. Furthermore, all this is done in ASCII string format, so you don't have to be familiar with hexadecimal. This is especially helpful for real numbers, where 3.141592 or 2.314E-12 makes much more sense than some cryptic hexadecimal numbers. DFD converts the numbers you type into their proper internal representation, and converts their internal representation to ASCII strings before displaying or dumping. DFD even lets you translate data to and from different languages. For instance, if you've written a Turbo Pascal program that stores tons of data and need this data to be read and written by a Microsoft Pascal or Computer Innovations C program or Turbo C program, DFD makes it possible. DFD can change data from one language format to another, and DFD includes a semi language of its own called AOL for Assignment Oriented Language. DFD works by scanning your Pascal or C source code for the RECORD or STRUCT statement describing your record layout. It then makes a data dictionary containing all the information it needs to know about your datafile such as offsets, variable names, types, lengths, etc. DFD DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Overview Page 1-2 What is DFD? supports up to 700 variable names per datafile, up to 6 dimensions per array (7 in the case of strings in C), up to 1000 tag names (array subscripts that have been "#define'd" in C or equated to values in Pascal), and up to 700 comments. Your RECORD or STRUCT statements may have nested (referenced) RECORD and STRUCT statements and CASE and UNION statements. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Overview Page 1-3 What You Need What You Need DFD works on all IBM and compatibles ranging from the XT to the entire PS/2 series of microcomputers. DFD was designed to work with color monitors - some monochrome monitors may not work properly with DFD. A fixed disk and 512K RAM is recommended. A printer connected to LPT1. You should also have a copy of Borland's Turbo Pascal, Borland's Turbo C, Microsoft Pascal, Microsoft C, or Computer Innovation's C86 compiler depending on which language you are using. DFD operates under the IBM PC-DOS operating system version 2.xx and above and all current versions of the MS-DOS operating systems. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Overview Page 1-4 Getting Started Getting Started For your convenience, the distribution disk is not copy protected. The first thing you should do is make a backup copy of the diskette with the DOS "diskcopy" command. When this is done, put the distribution diskette in a safe place, and use the backup copy only. To install DFD on your hard disk, place the backup diskette you made into disk drive A:, shut the drive door, and enter the following: C: MD C:\DFD CD C:\DFD COPY A:\*.* C:\DFD When this is complete, remove the diskette from drive A: and put it away. Next take a directory (DIR) of what you've placed on your hard disk. There will be 2 files labeled DFD.EXE and DFD.SCR in the subdirectory along with some other files. These two files comprise the DFD program. The "other" files are: Include Files for C: PASTYPES.H - "#include" with C programs. Use these data types. Scanner programs (Pass 1): PASSCAN.EXE - Pascal scanner program. CSCAN.EXE - C scanner program. Dictionary Builders (Pass 2): MSPA2DAD.EXE - Dictionary Builder program for Microsoft Pascal. TPAS2DAD.EXE - Dictionary Builder program for Borland's Turbo Pascal. CIC2DAD.EXE - Dictionary Builder program for Computer Innovations C. TC2DAD.EXE - Dictionary Builder program for Borland's Turbo and MS C Dictionary Utility Programs: DADRPT.EXE - Utility program to produce a report of a dictionary. DADSORT.EXE - Utility program to alphabetically sort a dictionary. DADUNIQ.EXE - Utility program to make duplicate member names unique. DAD2SRCE.EXE - Utility program to make source code from a dictionary. Demo Files: DEMO.REC - Demo source file for Turbo Pascal DEMO.DB - Demo database (data file) for Turbo Pascal Read or print this file: READ.ME - Latest information not in this user's manual. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-1 Concept Data Dictionaries Defined A data dictionary is a direct access or random file which contains information about your data file or database layout. The DFD system creates data dictionaries (files with an extension of ".DAD") from your source code. These DAD (DAta Dictionary) files contain symbol tables, offsets, variable types, and other kinds of information about your database. DFD works with these DADs to determine exactly where everything in the database is located - by variable name. Your record layout is limited to describe a maximum 64K of data, however, the data file or database has no limitation - data files or databases are usually repetitions of your record layout and can therefore be much larger than you could fit on your fixed disk. DADs are the universal language of DFD. Whether your data is stored from a Pascal or C program DFD knows just how to interpret and manipulate it. To create a DAD, you must first translate your source code to an intermediate type of source language. This is done by a Scanner program - either PASSCAN.EXE for Pascal, or CSCAN.EXE for C programs. This intermediate source file is then used as input to the Dictionary Builder Program which creates the DAD. Dictionary Builders currently available are for Microsoft Pascal, Borland's Turbo Pascal, Computer Innovations "C86" C compiler, and Borland's Turbo C compiler. The rest of this section deals with different languages and compilers, and the syntax the scanner programs expect you to follow. Though they follow the standards of the language you're programming in, they have stricter rules and tend to be a little less lenient than an actual compiler. The scanner and DAD builder programs operate on TYPEs, more specifically, RECORD types for Pascal, and STRUCT types for C. Whenever you build a data dictionary, the dictionary builder programs report the size of the structures or records. It is a good idea to write a short program to print the size of the structures or records you're using to make sure that your compiler and the dictionary builder both agree on these sizes, if they don't you've done something wrong. Note that the Scanner Programs produce an intermediate file with an extension of ".RRR", and the DAD builder programs produce three files with extensions of ".DAD", ".TAD", and ".KAD". These three files are the ones that are used by the DFD program. ".DAD" files are the data dictionary files themselves. ".TAD" files are the Tag dictionary files, and ".KAD" files are the comment dictionary files (named ".kad" so as not to interfere with cad/cam programs using an extension of ".cad", and to keep the convention of *.?ad straight). Note that if a DAD builder program finds an error, it refers to the line number of the intermediate file - the file with an extension of ".RRR". DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-2 Turbo Pascal Syntax for Turbo Pascal Users Since the scanner program is not a compiler, you should edit your source files and remove all code except for RECORD statements. The scanner ignores code and only looks for RECORD statements. The presence of code slows the process down. The Turbo Pascal DAD builder understands the following scalar data types: INTEGER LONGINT BYTE REAL BOOLEAN CHAR and the type: STRING It also understands the type: RECORD and the variant type: CASE Any of the scalar types, and the STRING type can be dimensioned (an array) up to 6 dimensions as in the following example: TEST1 : ARRAY[1..5,4..10,3..10,1..10,2..8,0..1] of INTEGER; Also, a variable reffering to a RECORD type can be dimensioned by the same rules: ABC = RECORD A : BYTE; B : ARRAY[1..6,3..9] OF STRING[10]; C : REAL; END; DEF = RECORD D : ARRAY[1..4,2..6] OF ABC; E : CHAR; F : INTEGER; END; In the above example, DEF.D is a two-dimensional array of type ABC. In this fashion, the ABC record is treated as an array of 20 ABC records DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-3 Turbo Pascal when referenced by DEF.D[x,y], therefore, DEF.D[x,y] in this example is a REFERENCE to another record (where x and y are subscripts). Note: If you're using Microsoft Pascal, STRING[10] is equivalent to LSTRING(10), and all STRING types in this section are equivalent to LSTRING types in Microsoft Pascal. See the section on Microsoft Pascal for additional data types and features not covered in this Turbo Pascal section. Variable Names are significant to 31 characters and should start with an alphabetic character. Important: All variable declarations are one per line. That is, you cannot do: a,b,c : integer; {wrong} or a, {wrong} b, {wrong} c : integer; {wrong} you must do: a : integer; {correct} b : integer; {correct} c : integer; {correct} Comments are understood by the Scanner with the 3 following rules: 1 - Only "{" and "}" are recognized as comments. "(*" and "*)" are invalid and should be changed to the curly bracket types. 2 - Both the "{" and "}" must appear on the same line! Comments cannot be split among multiple lines. 3 - Nested comments (comments within comments) are not allowed. Array subscript ranges must be positive whole numbers, or DAD "TAGS". DAD "TAGS" will be explained later. A maximum of 700 variable names, (including RECORD names) are allowed. Nested RECORDS are allowed by REFERENCE only. In other words, a RECORD must NOT have another RECORD statement in it, but it can REFER to another record type such as the DEF.D record refers to the ABC record in the previous example. CASE syntax (variant part of a RECORD) is somewhat different than the normal syntax. It consists of the word CASE on a single line. The tag, type, and "of" are ignored. The "(" and ")" parts are to be on lines by DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-4 Turbo Pascal themselves. The following example may help clarify this: Name = record FamilyName : string[32]; ChristianNames : array[1..3] of string[16]; end; Date = record Day : byte; Month : byte; Year : integer; end; Person=record PersonName : Name; Birthdate : Date; CASE citizen: ( BirthPlace : Name; ) Alien: ( CountryOfOrigin : Name; DateOfEntry : Date; PermittedUntil : Date; PortOfEntry : Name; ) End; Note that the above example is taken from the Turbo Pascal Reference Manual. Also note that the Date record in this example does not match the Date record in the Turbo Pascal Reference Manual. This is because the dictionary builder is not a compiler, and therefore only understands standard SCALAR and STRING data types. In case you don't have the Turbo Pascal Reference Manual handy, their version of the date record is as follows: Date = record Day : 1..31; Month : (Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec); Year : 1900..1999; end; Reiterating, the syntax the scanner and dictionary builders are expecting for these kinds of records are (via example): Date = record Day : byte; Month : byte; Year : integer; end; DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-5 Turbo Pascal Note how everything is converted to their standard scalar types. User defined scalars and subranges are not supported, since the DAD builder only needs to know about standard data types. Subranges of up to 256 elements are of the "byte" type, and higher than 256 are of the "integer" type. One final note is that "SOMENAME=RECORD" must appear on a line by itself, and "END;" must also appear on a line by itself. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-6 Turbo Pascal - Comments Comments As mentioned earlier, comments are of the curly bracket type ("{" and "}"). Each comment must appear on a single line and not split accross multiple lines. Comments must not be nested (comment within a comment). As the compiler uses metacommands or compiler directives within comments (these are ignored by the scanner and DAD builder programs), the scanner and DAD builder programs will also remember your comments. To remember your comments, they sould appear after the semicolon of standard scalar types as follows: Phone : string[10]; { This is for your phone number } ID : integer; { Holds your user id } Comments should be no longer than 80 character in length. As another feature, comments of this type beginning with 2 "#" characters, will be ignored by DFD (data file debugger). As an example: Phone : string[10]; { This is for your phone number } ID : integer; {## Holds your user id } When DFD lists your variables, ID will not be listed. Therefore, ID is not accessible to the DFD user for modification, listing, or anything else. This is sort of a built-in protection DFD offers by making certain fields unavailable to the user. Make sure the "#" characters are the first 2 characters immediately following the left curly bracket. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-7 Turbo Pascal - DAD "Tags" When working with arrays, it is sometimes more convenient to use a descriptive name for the subscript range rather than a range of numbers. This is allowed with the "{#START_SET}" and "{#END_SET}" DAD directives. The names come from "Start defining a set of tags", and "End defining a set of tags". Do not get the words "set" and "tags" confused with the standard Pascal meanings of these words. An Example would help to clarify this: {#START_SET} MONTH=1..12; YEAR=1900..2000; DAY=1..7; HOUR=1..24; {#END_SET} Info = Record MonthTable : array[MONTH] of string[9]; YearTable : array[YEAR] of integer; DayTable : array[DAY] of byte; HourTable : array[HOUR] of byte; MmDdYy : array[MONTH,DAY,YEAR] of string[20]; end; With this method, DFD will prompt you for subscripts using something like "MONTH (1 to 12)", rather than just "(1 to 12)". The above example is equivalent to the following: Info = Record MonthTable : array[1..12] of string[9]; YearTable : array[1900..2000] of integer; DayTable : array[1..7] of byte; HourTable : array[1..24] of byte; MmDdYy : array[1..12,1..7,1900..2000] of string[20]; end; The rules for defining DAD TAG's are simple: - No more than 1000 DAD TAG's can be defined in any given source record. - TAG names can be a maximum of 15 characters in length and should begin with a letter of the alphabet. - The TAG name should start in column 1, be followed immediately by an "=" character, and the "=" character should be followed immediately by one (and one only) range. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-8 Turbo Pascal - DAD "Tags" - The TAG range must contain whole numbers - no real or negative numbers are allowed. - Do Not forget to start TAG descriptions without a {#START_SET} and end them with a {#END_SET} or they will be ignored. The scanner only looks for and processes RECORD statements unless it finds these directives! Once a set of TAG's have been defined, you may use them freely anywhere an array subscript range can be used (as in the above example). DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-9 Turbo Pascal - Creating the DAD Creating the DAD There are two steps two creating the DAD. The first step is to run the scanner program. The scanner translates your source code into an intermediate file with an extension of ".RRR". So if your source code filename is "TEST.PAS" or "TEST.REC", the scanner will create an intermediate file with a filename of "TEST.RRR". The syntax for using the Scanner is: PASSCAN TEST.PAS PERSON Here we assume that TEST.PAS in the name of your source file, but it can be anything you like. We also assume that the name of your main RECORD statement is PERSON in this example, however it could have been any record name that happens to be the main record of your program. The TEST.PAS source file might look something like this: {#START_SET} CHRISTIAN_NAMES=1..3; {Don't forget - Maximum of 15-char TAG name} {#END_SET} Name = record FamilyName : string[32]; ChristianNames : array[CHRISTIAN_NAMES] of string[16]; end; Date = record Day : byte; { Day of week } Month : byte; { Month of Year } Year : integer; { Year } end; DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-10 Turbo Pascal - Creating the DAD Person=record PersonName : Name; Birthdate : Date; CASE citizen: ( BirthPlace : Name; ) Alien: ( CountryOfOrigin : Name; DateOfEntry : Date; PermittedUntil : Date; PortOfEntry : Name; ) End; If any errors are reported, you must correct them before running the DAD builder program. If all goes well, you can now run the DAD builder program: TPAS2DAD TEST NOTE: If you're using Microsoft Pascal, use the Microsoft Pascal DAD Builder Program: MSPA2DAD TEST Do not supply a filename extension, as it will automatically assume an extension of ".RRR". In the above example, the DAD builder program will look for the file TEST.RRR. If the DAD builder program detects any errors, it refers to the line number in the ".RRR" file. You should look at the line number in that file to determine where in your real file (ie: TEST.PAS) to look for your error. When the DAD builder program finishes, it will print the number of bytes of each RECORD it finds, and these numbers should be checked for accuracy. One way to do this is to write a quick program that prints the sizes of each of the RECORDs and make certain these numbers match. DO NOT EVER ATTEMPT TO RUN DFD WITH YOUR DICTIONARIES UNLESS THESE NUMBERS MATCH!!! - YOU COULD DESTROY YOUR DATA!!! The exception to this rule comes with Microsoft Pascal (or other languages that align their data on word boundaries). The DAD builder program prints record sizes exactly and Microsoft Pascal will always report these sizes as an even number of bytes. So in the case that the DAD builder reports a record as being 17 bytes and Microsoft Pascal DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-11 Turbo Pascal - Creating the DAD reports it as being 18 bytes, you're still ok ...Microsoft merely adds this extra byte to make it an even number - DFD does take this into account. If the numbers match - congratulations! You're now ready to run the DFD program and do all kinds of things to your datafiles or databases. You may now go to the section on using DFD, but before you do, you should be aware of one more thing. Since Pascal, unlike C, allows you to have duplicate member names in different records, you will have to make those names unique so that no one variable name appears more than once. Don't worry - you won't have to use an editor and painfully change everything by hand. You can use the DAD utility program DADUNIQ to do this for you. To accomplish this, you'll want to run the utility program on the dictionary you've just created: DADUNIQ TEST Do not supply an extension because this utility program automatically appends ".DAD" to the name and searches for TEST.DAD in this example. Variable names must be unique otherwise there will be no guarantee as to just which variable you are referring to when you are in DFD. The unique names this utility makes will be transparent to you since it uses invisible characters, and will therefore appear to be unchanged to you when in the DFD program. In most cases, this utility program will run successfully, but occasionally it will fail if your duplicate member names are close to the 31-character limit. If you have a 28-character variable name (member name) that appears 4 times, the DADUNIQ program will run successfully, but if it appears 5 or more times, DADUNIQ will fail. The reason for this is because DADUNIQ makes variable names unique by appending 1 invisible character to the 2nd occurrence of a variable name, bringing the name to 29-characters, the 3rd occurrence makes it 30 characters long, the 4th 31 characters, and the 5th would put it over the limit. DADUNIQ will alert you if this happens. If you're using Microsoft Pascal and were told to read this section on Turbo Pascal, you may now go back to the section on Microsoft Pascal for additional information on features not supported by Turbo Pascal. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-12 Microsoft Pascal Microsoft Pascal If you haven't read the section on Turbo Pascal, please read that section now. Microsoft Pascal follows the same conventions as Turbo Pascal with a few additional features. When you've finished reading the section on Turbo Pascal, you may then come back to this section and continue on the features and additional support for Microsoft Pascal users. Please read the section on Turbo Pascal now! Now that you've read the section on Turbo Pascal, here is the list of the scalar data types that Microsoft Pascal supports: SINT BOOLEAN BYTE CHAR WORD INTEGER4 INTEGER REAL8 REAL Microsoft Pascal also understands the types: LSTRING (same as Turbo Pascal STRING) STRING (an array of characters - not a variable length string) and of course: RECORD CASE Note that while Turbo Pascal uses variable length strings of the form: NAME : STRING[10]; Microsoft's equivalent is: NAME : LSTRING(10); Everything else discussed in the section on Turbo Pascal also applies to Microsoft Pascal, except that Microsoft Pascal has the additional scalar data types that Turbo Pascal doesn't have. These are SINT, WORD, INTEGER4, REAL8, LSTRING (same as Turbo's STRING) and STRING. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-13 Microsoft Pascal - Additional Features Microsoft Pascal has some additional features not present in Turbo Pascal. These additional features have also been incorporated into the DAD builder for Microsoft Pascal. Comments In addition to the curly brackets "{" and "}" to delimit comments, you may use an exclamation mark ("!") to indicate a comment. The "!" means that the entire line of source code from that point on is to be treated as a comment. Also note that just like the Turbo Pascal DAD builder, the older "(*" and "*)" delimiters of comments are not detected and should be changed to the "{" and "}" curly brackets. Bracketed Offsets Microsoft Pascal also offers bracketed offsets not found in Turbo Pascal. Most people don't know of them, nor do they use them. But where space is vital, or something absolutely has to start at a certain offset, the DAD builder will also support these bracketed offsets. Basically, bracketed offsets allow the programmer to override the way Microsoft Pascal aligns everything on word boundaries. Once you use a bracketed offset in Microsoft Pascal, you must always use it. You must also access the data in a certain fashion or you may overwrite other data - Consult your Microsoft Pascal user's manual for more details and remember to follow it's conventions when using DFD. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-14 Borland's Turbo C, MS C and Computer Innovations C86 ("C") Since the scanner program is not a compiler, you should edit your source files and remove all code except for STRUCT statements. The scanner ignores code and only looks for STRUCT statements. The presence of code slows the process down. The datatypes that the C DAD builders understand have been set up in a file of "#define's" in the file "pastypes.h" on the distrubution disk. You will want to copy or "#include" this file with your source file. The Computer Innovations "C" (hereinafter reffered to as "C86") and Turbo C DAD builders understand the following scalar data types: unsigned int (or can use WORD) int (or can use INTEGER) unsigned long (or can use UNSLONG) long (or can use INTEGER4) float (or can use REAL) double (or can use REAL8) Since there are so many different ways to use the type "char" or "unsigned char", the DAD builder has eliminated the data type altogether and replaced it with the following data types: SINT - signed char (values of -127 to 127) BOOL - unsigned char (can take a value of 0 or 1) BYTE - unsigned char (can take a value of 0 to 255) CHAR - unsigned char (can hold ASCII character values) ZSTRING - unsigned char (ASCII Z-string - variable length string) STRING - unsigned char (holds a string of chars - fixed length) It also understands: struct and the variant type: union Any of the scalar types, and the different character types can be dimensioned (an array) up to 6 dimensions as in the following example: int test1[5][10][6][4][8][2]; or INTEGER test1[5][10][6][4][8][2]; Also, a variable reffering to a STRUCT type can be dimensioned by the same rules: struct abc { DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-15 Borland's Turbo C, MS C and Computer Innovations C86 ("C") byte a; ZSTRING b[6][7][10]; float c; }; struct def { struct abc d[4][5]; CHAR e; int f; }; In the above example, def.d is a two-dimensional array of type abc. In this fashion, the abc record is treated as an array of 20 abc records when referenced by def.d[x][y], therefore, def.d[x][y] in this example is a REFERENCE to another record (where x and y are subscripts). Variable Names are significant to 31 characters and should start with an alphabetic character. Important: All variable declarations are one per line. That is, you cannot do: int a,b,c; /* wrong */ or int a, /* wrong */ b, /* wrong */ c; /* wrong */ you must do: int a; /* correct */ int b; /* correct */ int c; /* correct */ With two of the new data types introduced above, STRING and ZSTRING, a variable can actually have up to 7 dimensions instead of the limit of 6 imposed above. The reason is that STRING and ZSTRING refer to a string of one or more characters. This means that you still have the limitation of 6 dimensions, but the last dimension (or 7th in the maximum case) tells just how many characters the variable is supposed to be a string of. The ZSTRING type refers to your standard null-terminated string (also known as an ascii zstring). So if you want to have a maximum of ten characters in a variable length string, it should be declared as "ZSTRING somename[11];" in order to accomodate the null byte at the end of the string. "ZSTRING somename[5][5][11];" declares a 2-dimensional (5 by 5) variable length strings with a length of 10 characters each (plus an extra for the null byte at the end). DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-16 Borland's Turbo C, MS C and Computer Innovations C86 ("C") The STRING type might not get any use, but it defines a fixed length string and is not null terminated. Therefore, "STRING somename[10];" is a declaration of a 10-character fixed length string. There is no null byte. Variable Names are significant to 31 characters and should start with an alphabetic character. Comments are understood by the Scanner with the 3 following rules: 1 - Only "/*" and "*/" are recognized as comments. 2 - Both the "/*" and "*/" must appear on the same line! Comments cannot be split among multiple lines. 3 - Nested comments (comments within comments) are not allowed. Array subscript declarations must be positive whole numbers, or DAD "TAGS". DAD "TAGS" will be explained later. A maximum of 700 variable names, (including STRUCT names) are allowed. Nested STRUCTS are allowed by REFERENCE only. In other words, a STRUCT must NOT have another STRUCT type ("struct somename {" or "struct {") in it, but it can REFER to another record type such as the def.d record refers to the abc record in the previous example. The exception to the appearance of a "struct {" within a struct type is when UNIONs are involved. UNION syntax is somewhat different than the normal syntax. It is designed to closely follow the Pascal syntax in order to keep DAD's a universal language for DFD. It consists of the characters "union {" on a single line. The "(" and ")" parts that are used in Pascal are replaced with "struct {" and "} uniquename;" respectively and must appear on separate lines by themselves. The following example may help clarify this: struct Name { STRING FamilyName[32]; STRING ChristianNames[3][16]; }; struct Date { BYTE Day; BYTE Month; int Year; }; DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-17 Borland's Turbo C, MS C and Computer Innovations C86 ("C") struct Person { struct Name PersonName; struct Date Birthdate; union { /* variant part */ struct { struct Name BirthPlace; } s0; struct { struct Name CountryOfOrigin; struct Date DateOfEntry; struct Date PermittedUntil; struct Name PortOfEntry; } s1; } u0; }; For comparison purposes, the equivalent Pascal source record would look like this: Name = record FamilyName : string[32]; ChristianNames : array[1..3] of string[16]; end; Date = record Day : byte; Month : byte; Year : integer; end; Person=record PersonName : Name; Birthdate : Date; case byte of citizen: ( BirthPlace : Name; ) Alien: ( CountryOfOrigin : Name; DateOfEntry : Date; PermittedUntil : Date; PortOfEntry : Name; ) End; After some observation, you'll notice the similarities to Pascal: DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-18 Borland's Turbo C, MS C and Computer Innovations C86 ("C") Pascal C Purpose somename=record struct somename { start type definition end; }; end type definition case union { begin variant description ( struct { begin a part of variant ) } somename; end a part of variant } somename; end variant description Unfortunately, this syntax is required to keep C and Pascal universal to the DFD program and the dictionary formats. This means UNIONs cannot appear by themselves, they must always appear as the last (or variant) part of the STRUCT (record) as is required by the Pascal language. This means that UNION's such as: union u { int a; char b; real c; }; would have to be re-written as follows: struct u { /* u=record */ union { /* case byte of */ /* s1: */ struct { /* ( */ int a; /* a : integer; */ } s1; /* ) */ /* s2: */ struct { /* ( */ char b; /* b : char; */ } s2; /* ) */ /* s3: */ struct { /* ( */ float c; /* c : real; */ } s3; /* ) */ } u1; /* end; */ }; Sorry about the inconvenience - it's one more reason to hate Pascal! DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-19 Turbo C, MS C and Computer Innovations C86 ("C") - Comments Comments As mentioned earlier, comments are consist of "/*" and "*/". Each comment must appear on a single line and not split accross multiple lines. Comments may not be nested. The scanner and DAD builder programs will remember your comments. In order to do this, they should appear after the semicolon of standard scalar types as follows: STRING phone[10]; /* This is for your phone number */ int id; /* Holds your user id */ Comments should be no longer than 80 characters in length. As another feature, comments of this type beginning with 2 "#" characters, will be ignored by DFD (data file debugger). As an example: STRING Phone[10]; /* This is for your phone number */ int ID; /*## Holds your user id */ When DFD lists your variables, ID will not be listed. Therefore, ID is not accessible to the DFD user for modification, listing, or anything else. This is sort of a built-in protection DFD offers by making certain fields unavailable to the user. Make sure the "#" characters are the first 2 characters immediately following the "/*". DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-20 Turbo C, MS C and Computer Innovations C86 ("C") - DAD "Tags" When working with arrays, it is sometimes more convenient to use descriptive names for subscripts rather than a number. This is allowed with the "/*#START_SET*/" and "/*#END_SET*/" DAD directives. The names come from "Start defining a set of tags", and "End defining a set of tags". An example would help clarify this: /*#START_SET*/ #define MONTH 12 #define DAY 7 #define HOUR 24 /*#END_SET*/ struct Info { ZSTRING MonthTable[MONTH][10]; BYTE DayTable[DAY]; BYTE HourTable[HOUR]; int MmDd[MONTH][DAY]; }; With this method, DFD will prompt you for subscripts using something like "MONTH (0 to 11)", rather than just "(0 to 11)". Note that for ZSTRINGs and STRINGs, the very last dimension must be an absolute number, not a TAG. The above example is equivalent to the following: struct Info { ZSTRING MonthTable[12][10]; BYTE DayTable[7]; BYTE HourTable[24]; int MmDd[12][7]; }; The rules for defining DAD TAG's are simple: - No more than 1000 DAD TAG's can be defined in any given source file. - TAG names can be a maximum of 15 characters in length and should begin with a letter of the alphabet. - The TAG definition should start with the "#define" (without quotes) in column 1, be followed immediately by a space, and the space should be followed by the TAG name. The TAG name should be followed by one or more spaces, and a whole number. - The TAG number must be a whole number - no real or negative DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-21 Turbo C, MS C and Computer Innovations C86 ("C") - DAD "Tags" numbers are allowed. - Do Not forget to start TAG descriptions with a /*#START_SET*/ and end them with a /*#END_SET*/ or they will be ignored. The scanner only looks for and processes STRUCT statements unless it finds these directives! Once a set of TAG's have been defined, you may use them freely anywhere an array subscript can be used (as in the above example) except for the last subscript of a STRING or ZSTRING. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-22 Turbo C, MS C and C86 ("C") - Creating the DAD Creating the DAD There are two steps two creating the DAD. The first step is to run the scanner program. The scanner translates your source code into an intermediate file with an extension of ".RRR". So if your source code filename is "TEST.C" or "TEST.REC", the scanner will create an intermediate file with a filename of "TEST.RRR". The syntax for using the Scanner is: CSCAN TEST.C PERSON Here we assume that TEST.C is the name of your source file, but it can be anything you like. We also assume that the name of your main STRUCT statement is PERSON in this example, however it could have been any STRUCT name that happens to be the main STRUCT of your program. The TEST.C source file might look something like this: /*#START_SET*/ #define CHRISTIAN_NAMES 3 /*Remember - Max. of 15-char TAG name*/ /*#END_SET*/ struct Name { ZSTRING FamilyName[33]; ZSTRING ChristianNames[CHRISTIAN_NAMES][17]; }; struct Date { BYTE Day; /* Day of week */ BYTE Month; /* Month of Year */ int Year; /* Year */ }; DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-23 Turbo C, MS C and C86 ("C") - Creating the DAD struct Person { struct Name PersonName; struct Date Birthdate; union { struct { struct Name BirthPlace; } citizen; struct { struct Name CountryOfOrigin; struct Date DateOfEntry; struct Date PermittedUntil; struct Name PortOfEntry; } Alien; } u1; }; If any errors are reported, you must correct them before running the DAD builder program. If all goes well, you can now run one of the DAD builder program: for Turbo C: TC2DAD TEST for MS C: TC2DAD TEST /A for C86: CIC2DAD TEST NOTE for Turbo C Users: Turbo C lets you choose how it will store its data in one of 2 ways: byte (unaligned) and word aligned. The default is byte (unaligned). To build a dictionary that aligns on word boundaries, append a "/a" (without quotes) to the input filename. The "/a" must be supplied for programs compiled with the "-a" compiler switch (word align). NOTE for Microsoft C: Microsoft C lets you choose how it will store its data as with the Turbo C compiler. However, defaults are reversed. The Microsoft C compiler defaults to word alignment so you must supply the "/A" parameter. If your programs were compiled with the "/Zp" compiler switch (packed structures), do not supply the "/A" paramter. Do not supply a filename extension, as it will automatically assume an extension of ".RRR". In the above example, the DAD builder program will look for the file TEST.RRR. If the DAD builder program detects any errors, it refers to the line number in the ".RRR" file. You should look at the line number in that file to determine where in your real file (ie: TEST.C) to look for your error. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Data Dictionaries Page 2-24 Turbo C, MS C and C86 ("C") - Creating the DAD When the DAD builder program finishes, it will print the number of bytes of each STRUCT type it finds, and these numbers should be checked for accuracy. One way to do this is to write a quick program that prints the sizes of each of the STRUCTs and make certain these numbers match. If you don't know how to do this, use DAD2SRCE.EXE with the "/c" option for an example of how to code this. DO NOT EVER ATTEMPT TO RUN DFD WITH YOUR DICTIONARIES UNLESS THESE NUMBERS MATCH!!! - YOU COULD DESTROY YOUR DATA!!! If the numbers match - congratulations! You're now ready to run the DFD program and do all kinds of things to your datafiles or databases. You may now go to the section on using DFD, but before you do, you should be aware of one more thing. Some C compilers allow you to have duplicate member names in different structs. You will have to make those names unique so that no one variable name appears more than once. Don't worry - you won't have to use an editor and painfully change everything by hand. You can use the DAD utility program DADUNIQ to do this for you. To accomplish this, you'll want to run the utility program on the dictionary you've just created: DADUNIQ TEST Do not supply an extension because this utility program automatically appends ".DAD" to the name and searches for TEST.DAD in this example. Variable names must be unique otherwise there will be no guarantee as to just which variable you are referring to when you are in DFD. The unique names this utility makes will be transparent to you since it uses invisible characters, and will therefore appear to be unchanged to you when in the DFD program. In most cases, this utility program will run successfully, but occasionally it will fail if your duplicate member names are close to the 31-character limit. If you have a 28-character variable name (member name) that appears 4 times, the DADUNIQ program will run successfully, but if it appears 5 or more times, DADUNIQ will fail. The reason for this is because DADUNIQ makes variable names unique by appending 1 invisible character to the 2nd occurrence of a variable name, bringing the name to 29-characters, the 3rd occurrence makes it 30 characters long, the 4th 31 characters, and the 5th would put it over the limit. DADUNIQ will alert you if this happens. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-1 Starting DFD Using DFD Once you have made your data dictionaries (DAD's) with the DAD builder programs, you can use DFD. Before using DFD, it is more than wise to make a copy of your data files or databases under a different name - just in case you accidentally ruin existing data by making mistakes. It is your responsibility to insure this data integrity. Before going on with this section, go through the DEMO section in this manual to get familiarized with DFD if you haven't already done so. There are 2 ways of starting DFD: Method 1: DFD Method 2: DFD FILENAME With method 1, entering DFD on the DOS command line starts the program, and anytime you choose a 'dump' option when within the DFD program, the dump will be routed to your printer at LPT1: With method 2, entering DFD and some FILENAME, on the DOS command line will start the program just as with method 1, except that anytime you choose a 'dump' option when within the DFD program, the dump will be routed to FILENAME instead of to your printer. Note that if FILENAME does not exist, it will be created. If FILENAME does exist, it will be appended to. Once DFD is up and running, you will be presented with a colorful screen (unless you're using a monochrome monitor). The cursor will be placed on the first dictionary name field (labeled "Dictionary01:"). The screen will look similar to this: DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-2 Starting DFD ┌───[ Data File Debugger (DFD) - (C)Copyright 1986, 1987 - Gilmore Systems ]───┐ │Dictionary01: Data: │ │Dictionary02: Data: │ │Dictionary03: Data: │ │Dictionary04: Data: │ │Dictionary05: Data: │ │Dictionary06: Data: │ │Dictionary07: Data: │ │Dictionary08: Data: │ │Dictionary09: Data: │ │Dictionary10: Data: │ │Dictionary11: Data: │ │Dictionary12: Data: │ │Dictionary13: Data: │ ├─[F1=Help F2=Continue F3=Swap F4=Clear F9=DOS F10=Quit]──────────────────┤ │Dict#: #Data Records: Rec: │ Tag ( ) Dimens ( ) Subsc│ │Varname: │1 │ │Rec( ) │2 │ │Ref( ) │3 │ │Type: Language: │4 │ │Length: Sequence Number: │5 │ │Main Offset: Record Offset: │6 │ ├────────────────────────────────[ D A T A ]────────────────────────────────┤ │ │ └───────────────────────────[ ]───────────────────────────┘ Note that the DFD display screen is divided into two halves. The top half which is for you to enter dictionary names and their associated data files, and the bottom part which is for data manipulation and display. The next two sections deal with these two halves. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-3 Top Half of the DFD Display Screen You may enter your first dictionary name here. Note that you have a maximum of 8 characters to supply this name. All dictionaries and related files (files with an extension of ".DAD", ".TAD", and ".KAD") should be on the default drive and directory. To get a list of dictionaries currently on the default drive and directory, hit the function key F1. Do not supply an extension when answering the "DictionaryXX:" prompts, as DFD automatically looks for an extension of ".DAD". After entering a dictionary name, hit the ENTER key and the cursor will move to the "Data:" field. At this field, you are to supply a data file or database name described by the dictionary name to it's left. You can supply an optional drive letter and path (ie: C:\DFD\TESTDATA.FIL). If you do not supply a drive letter, the current drive is assumed. If you do not supply a path, the current path is assumed. After you've entered the data file or database, hit the ENTER key and you'll be taken to the next field ("Dictionary02:"). Repeat the process for as many dictionaries and files you want to work with. If you hit the function key F1 while in a "Data:" prompt, you'll be asked what you want a directory of. It is equivalent to the DOS "dir ________" command, except you fill in the blank with drive, path, filename and wildcards. While entering dictionaries and filenames on the top portion, certain keys will do certain things. The INS key toggles insert mode, the DEL key deletes the character under the cursor and moves everything to the right of that character to the left by 1, the left and right cursor (arrow) keys work as expected, and the BACKTAB (Shift+Tab) key moves the cursor to the previous field. The F1 key was already mentioned, the F9 key lets you go into DOS, the F10 key quits the program (with your permission), the F4 key clears everything you've typed on the top portion of the screen, and the F2 key signals the end of dictionary and data file entry. F3 is identical to F2 when on the top half of the screen. The ESC key erases the entire field the cursor is on. When you've finished supplying the dictionary name(s) and data file name(s) you'd like to work with, hit the function key F2. DFD will then check all of the information you've entered and then take you to the bottom half of the screen where you can begin manipulating your data. If DFD can't find a dictionary name you've supplied, you'll be notified and the cursor will be placed at the dictionary prompt number in question. If you supply a dictionary to a dictionary prompt and fail to supply a data file name, you'll be beeped at and the cursor will be placed at the missing data file prompt. If you supply a data file name that doesn't exist, you'll be notified and DFD will ask you if you'd like it to create it for you. If you answer no, you'll be taken back to the invalid filename for correction. If you answer yes, DFD will prompt you as to how many data records you'd like the data file to have. After answering that question, DFD will create the data file for you, with all fields initialized with null's (binary zeroes). DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-4 Top Half of the DFD Display Screen Note: Data files or databases sometimes have a "header" as part of the file before the random part of the file starts. If this is the case, you must inform DFD how long this header is. For example, if the header is 30 bytes long and the data file name is TESTFILE.A, you would answer that "Data:" prompt with "TESTFILE.A,30". This informs DFD that the first record (record 0) starts at offset 30 (the 31st byte of the file). DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-5 Bottom Half of DFD Display Screen The cursor should now be located at the "Dict#:" prompt. If you enter a "1" here, you are referring to the dictionary name and associated data file you've supplied at the top half of the screen labeled "Dictionary01:" and "Data:". Type in the number of the dictionary you'd like to work with. (Usually "1" to start with) and hit ENTER. DFD will fill in the "#Data Records:" field with how many data records are in your data file, and take you to the "Rec:" prompt. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-6 Bottom Half of DFD Display Screen - "Rec:" prompt The "Rec:" prompt This prompt can be answered in 1 of 4 ways: The first way is to hit the BACKTAB (Shift+TAB) key. Doing this takes you back to the "Dict#:" prompt. The second way is to enter "/d". This will initiate the Dump procedure. If you entered "/d", you will get a "?" prompt in the field. You are to respond with the record number you want to dump (0 for the first, 1 for the 2nd, etc). If you'd like to dump the entire data file, answer with "0+". If there are 30 records, and you want to dump the last 5, answer with "25+". The dump will be routed to your printer or file depending on how you invoked the DFD program from DOS. If you wish to stop a dump in progress before it completes, simply hit F10. Dumps are an invaluable way of sending data through communication lines to mainframe or other computers not using the same data format as yours (just a thought). The third way is to enter "/z". This is the reverse of the Dump procedure. This takes an ASCII file as input, and "zaps" the database with the information in that file. This will be discussed later in the Advanced Section later in this manual. The last way is to supply the record number of the record you'd like to update or see. Note that record numbers start with 0, so that the first record in the file is record 0, the second record is record 1, and so on. The "#Data Records:" field filled in by DFD tells you how many data records there are in the file. If it says 3 for example, your choices here are 0, 1, or 2 for the first, second, and third records, respectively. Answer with 0 for now and hit ENTER. DFD will now present you with the first screenful of variable names for you to choose from. If you have a color monitor, note that the main record name is in magenta, and the word "RECORD" falls under the TYPE definition. The total record length is also given. Note that any REFERENCES to other records are in green and listed as REFERENCE under type. All other entries are member names in brown. You can move the cursor up and down to select the member you want. A variable is selected by hitting ENTER when you've positioned the cursor to the line containing the variable you want. Note that the line the cursor is on will be highlighted - if not, then you'll need to adjust the intensity or contrast dials on your monitor. Note that you cannot select a RECORD - only member names (brown) and REFERENCEs (green). If you select a REFERENCE, DFD will present you with the member names and other REFERENCEs (if any) of the subrecord you've chosen. To cancel selection, simply hit the ESC key. Note that if you press the function key F1, DFD will display the comment originally from your source code at the bottom. This will help to remind you what the field is to be used for, and you are also given an DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-7 Bottom Half of DFD Display Screen - "Rec:" prompt opportunity to modify the comment. Once you've selected a member name, DFD will take you back to the main screen where it will display the data immediately, or ask you for subscripts if you've chosen a dimensioned variable. If you've chosen a dimensioned variable, enter the subscripts of the the element you'd like to see at this time. The cursor should now be located at the "DATA" field, and display whatever data was in the variable you've chosen. If the display is blank, there was nothing there. At this point, you can either hit the function key F4 or the BACKTAB key to cancel, or you can overtype or type in the new data to be put into the field. If you choose to enter new data, hit the ENTER key when you're done. DFD will take you back to the "Dict#:" prompt when you're finished entering new data, or if you cancel data entry. It's that simple! The 4 prompt areas on the bottom half of the screen are "Dict#:", "Rec:", "Subsc", and "DATA". So far we've covered "Dict#:" and part of the "Rec:" prompt. More on the "Rec:" prompt will be covered under the "Advanced Secion" section of this manual. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-8 Bottom Half of DFD Display Screen - "Subsc" prompt The Subsc prompt field contains 6 entry fields - 1 for every dimension in a dimensioned variable. If the variable you've chosen is not dimensioned, the cursor will be located at the DATA prompt. If the selected variable is dimensioned (anywhere from 1 to 6 dimensions), the cursor will be placed at the first dimension prompt field. It is asking you to input the element number of that dimension. For example if the selected variable was declared as: varname : array[1..5,1..7] of integer; you would supply for the first dimension the element number which can range from 1 to 5, and then hit ENTER. For the second dimension prompt, you would respond with the 2nd dimension number which can range from 1 to 7 and hit ENTER. If there were 2 dimensions, the cursor would not move to the 3rd dimension prompt, but over to the DATA prompt. If you responded to the 2 dimension prompts with 2 and 4 respectively, you would be shown the data element associated with varname[2,4] at the DATA field. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-9 Bottom Half of DFD Display Screen - "D A T A" prompt The D A T A field (hereinafter reffered to as DATA) at the bottom of the screen contains the actual data value of what was in the file as described by the variable you've chosen. In the case of a string (this includes string, lstring, zstring) this field will be blank if nothing was there. In the case of "char" data, a single character will be displayed (note that a blank is also a char). In the case of reals (this includes real, real8, float, double) this field will be displayed in the simplist way. If the field contains "15.00" for example, it will simply be displayed "15". If it contains "-6.7" it will display "-6.7". If it contains "3.14" it will be displayed as "3.14". If it contains "0.0000007481" it will be displayed as "7.481000E-07". On display, the 6 most significant digits (to the right of the decimal) will be displayed. In all other cases, the display will be obvious. In any event, the cursor will be located at the first character of the display. You may overtype the data the display with new data and then hit ENTER to complete the update. Or you can cancel data entry (update) by pressing either F4 or BACKTAB (Shift + Tab). Other keys are available to you in the data field: ESC - erase the entire field (clear field) Cursor left - move cursor to previous character Cursor right - move cursor to next character Ins - Toggle Insert mode Del - Delete the character at the cursor Backspace - Destructive Backspace Home - Position cursor at beginning of field End - Position cursor at end of field F4 - Cancel update (data entry) of this field BACKTAB - Cancel update (data entry) of this field ENTER - Accept update and immediately update the data file The BACKTAB and ENTER keys have additional meanings when doing automatic prompted input of an array (dimensioned variable) - see the Advanced Section of this manual for more information. After you have ENTERed your new data or cancelled the update with F4 or BACKTAB, the cursor will be placed at the "Dict#:" prompt again (unless you are automatically prompted for array input - see the Advanced section of this manual). At this point you may just hit ENTER again to work with the same dictionary and data file (database) or enter a new dictionary number to work with. Note that if you work with the same dictionary again the cursor will immediately go to the "Rec:" prompt since this data dictionary is already in RAM. If you choose a new DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Using DFD Page 3-10 Bottom Half of DFD Display Screen - "D A T A" prompt dictionary number, it will take a couple of seconds longer since DFD has to load a new dictionary into RAM. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Advanced Section Page 4-1 Dimensioned Variables ("Subsc" Prompt Field) Whenever you are working with a dimensioned variable (array), you can do some advanced things at the "Subsc" prompt field. These are: /I - prompt for automatic array INPUT /F - FILL the array elements with identical data /D - DUMP the array elements /M - MODIFY the tagname given to this subscript range Using "/I" By entering "/I" (without quotes) as a response to a "Subsc" prompt, DFD will respond with a "?". The question mark is DFD's way of saying - Ok, I'll prompt you for array input - what subscript do you want to start with? You are then to overtype the "?" with the subscript number you want to start with. For example, if the selected variable was declared as: varname : array[0..4,1..7,2..6] of real; you could enter the "/I" at the first, second, or third "Subsc" prompt field. If "/I" was entered at the first field, the next two subscript field prompts will be filled in by DFD with 1 and 2. Data Entry would start at this point until the end of the array was reached. If you supply the "/I" response at the 2nd field, the first field entry would remain, and the 3rd field entry would be filled in by DFD as 2 and data entry would start from there. Some examples would help clarify this: Start prompted entry at varname[2,3,3] 2 3 /i ---> ? ---> 3 Start prompted entry at varname[4,1,2] /i ---> ? ---> 4 Start prompted entry at varname[0,3,2] 0 /i ---> ? ---> 3 The notation of "---> ? ---> n" means that after a "/i" a "?" will be displayed. You are to overtype the "?" with a number that is within the subscript range for this dimension. When the "?" prompt is answered with your response, the cursor will be DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Advanced Section Page 4-2 Dimensioned Variables ("Subsc" Prompt Field) placed in the DATA area and you may start data entry. Hitting ENTER enters the data you have supplied or whatever the data is that's currently displayed in the DATA area, and updates the data file immediately. The ENTER key also takes you to the next element in the array for data entry and updates the "Subsc" field to reflect which data element you are now being prompted for. Hitting BACKTAB (Shift+TAB) or F4 will cause cancellation of the current element and go back to the previous data element for entry - the "Subsc" field will be updated to reflect this. Hitting F10 cancels data entry altogether and goes back to the "Dict#:" prompt. Using "/F" The "/F" response (without quotes) means that you want to fill all elements in the array with the same piece of data. When you respond with a "/F", DFD responds with a "?". You are to overtype the "?" with the same kind of response that the "/I" prompt expects. Once the "?" prompt has been answered, the cursor will be moved to the DATA field, and you may enter the data that you'd like the array to be filled with. After hitting ENTER, DFD will update the entire array (or portion of the array depending on how you answered the "?" prompt) with that piece of data and immediately update your data file (database). Using "/D" The "/D" response (without quotes) tells DFD that you want to dump the contents of the array elements to the printer or to a file, depending on how you started the DFD program. DFD will respond to "/D" with a "?", and should be answered in the same fashion as with "/F" or "/I". If you wish to stop a dump in progress before it completes, hit F10. Using "/M" The "/M" response (without quotes) is an extra goodie that has no effect on your data. Instead, it modifies the tagname you supplied in your source code record layout to be associated with this particular subscript range. If there was no tagname given, here's your chance to create a tagname for the subscript range. Entering "/M" moves the curser to the "Tag" field - you may now overtype or enter a new tagname in this field, then hit ENTER to complete the tagname update. The cursor will then move back to the "Subsc" prompt where you can supply a subscript or "/I" or "/F" or "/D" or even "/M" again. Spaces will be ignored, so use the underscore ("_") character for readability just as you would in a high level language. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Advanced Section Page 4-3 Zapping (batch entry) Zapping (batch entry) In order to understand "zapping", you must first undestand "dumping", because zapping is the reverse of dumping. When you dump a data file, you get a file or printout (depending on how you started DFD) containing the name of the data file, the dictionary name, the date, time, language, the data file main-record-name and main-record-number, then the variable names and data contents. DFD requires that prior to making assignments, the file must start with the name of the data file main-record-name and main-record-number just the way a DFD dump does. This is discussed in more detail later. Study a printout of a DFD dump file. Once you are thoroughly familiar with the format, think of it as an "assignment oriented language" (or AOL). This means that you can take a dump file and edit it in a text editor to make any data changes you wish. Delete those you don't want. Add assignments that you do want. When finished editing your changes, simply save the file. This file can be used later as a "zap" file, or batch entry file. The next time you're at the "Rec:" prompt, try entering "/Z" (without the quotes). DFD will then ask you what filename to "zap" from. Use the filename of the file you just edited. DFD will now read this file and interpret it. To DFD, this is a file of assignments (or AOL) commands. These assignment commands are interpreted and carried out one at a time. DFD provides error messages on the printer during the "zap" process, so make sure your printer is ON during a "zap"! This method of "dumping", optionally editting, and "zapping" can be used as a means of transforming data from one language format to another (ie: Turbo Pascal data format to Microsoft data format or Computer Innovations data format). The AOL format is independant of computer language used. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Advanced Section Page 4-4 Assignment Oriented Language (AOL) Assignment Oriented Language (AOL) The Assignment Oriented Language (AOL) is a DFD language. It is written independant of different Pascal, C, or any other language dialect, although it resembles that of most languages. See the section on "zapping" for a brief introduction to AOL. Like most languages, the variable name is on the left of the equals sign, indicating this variable is the target of the assignment. It is followed by and equals (=) sign, which is followed by the data. The data rules are simple. Strings, Lstrings, Zstrings, or any type of string data is to be delimited by double quotation marks ("). Character data is to be delimited by single quotation marks ('). Whole numbers are digits and an optional minus (-) preceding the number. Real numbers follow the rules of whole numbers, but can also have a decimal point, and an E (to indicate E-Format numbers - your BASIC manual has a good explanation) which must be followed by plus or minus (+/-) and a number. This E format is also known as Scientific Notation. Summarizing: DATA TYPE DELIMITERS EXAMPLES string " " varname = "This is a string" varname = "This is longer " character ' ' varname = 'c' varname = '0' whole number none varname = 35 varname = -3265 real number none varname = 15 varname = 3.1415 varname = -7.6 varname = 2.768E-10 varname = -4.444E+3 dimensioned depends on string[3][2][6] = "some string" type character[2][5] = 'Y' somereal[4][18] = 33.752 somereal[100] = 3.621E-15 Just as with a language such as Pascal or C, you can refer to other records (subrecords of the main record). For example: work.supervisor[5].lastname = "Doe" Before any assignment statements are given, you must begin your file with the name for the data record (note the 3 asterisks): DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Advanced Section Page 4-5 Assignment Oriented Language (AOL) *** data record = "mainrec[0]." This informs DFD that the name of the main record is "mainrec" and that you are updating the first record in the data file ("mainrec[0]."), and that "mainrec[0]." is to precede all of the following variable names (if you use Microsoft Pascal, think of it as being similar to the "with" statement). This means that: person.lastname = "Smith" is interpreted by DFD as: mainrec[0].person.lastname = "Smith" and the first record gets updated. A data statement can occur anywhere in the AOL file. This enables you to change which record number in the data file or database is to be operated on by DFD for the AOL assignments following. For example: *** data record = "mainrec[5]." tells DFD that AOL assignments following this statement are to be used to update the 6th record in the file (0=first record, 1=second record, etc). Now: person.lastname = "Smith" is interpreted by DFD as: mainrec[5].person.lastname = "Smith" If, while in the process of "zapping" DFD finds any errors (such as a missing quote), DFD will display error messages on the printer, so you must have your printer on during a "zap". Error messages tell you what line number in the zap file had the error. You must edit these errors in a text editor to correct them. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Advanced Section Page 4-6 Converting Data to Other Languages Suppose you've written a Turbo Pascal program that has saved tons of data to a file and this file must be readable by a Microsoft Pascal program, or vice versa. This data could have been written to a file by any of the five currently supported language compilers and a need arises to convert the data to another language format. This can easily be done with DFD's "dump" and "zap" features. To use an example, take the demo source record layout file ("demo.rec") and copy it as "mspdemo.rec". "Demo.rec" is for Turbo Pascal users. To build a dictionary for Microsoft Pascal, edit the file "mspdemo.rec" that you just made a copy of in your favorite text editor. Change all occurences of " string[" to " lstring(" and don't forget to change the ending "]" of strings to ")" for lstrings. Next change all occurences of "real" to "real8". The reason for this is that a Turbo Pascal real is a 6-byte piece of data, whereas Microsoft Pascal has two types of reals: "real" and "real8". A Microsoft "real" is 4-bytes while a Microsoft "real8" is 8-bytes. A Turbo Pascal "real" being 6-bytes long can hold a larger number than a Microsoft Pascal "real", but a Microsoft Pascal "real8" can hold a larger number than a Turbo Pascal "real". You could automate these changes with DAD2SRCE.EXE explained later. After making these syntactical changes, save the file and run the Pascal scanner program: PASSCAN MSPDEMO.REC CUSTOMER Next run the Dictionary Builder program: MSPA2DAD MSPDEMO and a Microsoft Pascal Data Dictionary has been created. Note: If you haven't already created a Turbo Pascal DAD as outlined in the demo section of this manual, you may to so now by executing the following two lines at the DOS command prompt: PASSCAN DEMO.REC CUSTOMER TPAS2DAD DEMO Now you can start the DFD program, but do so with a dump filename as follows: DFD SAMPLE.DMP When the DFD main screen appears, respond to the first two "DictionaryXX:" and "Data:" prompts as follows: Dictionary01: DEMO Data: DEMO.DB Dictionary02: MSPDEMO Data: MSPDEMO.DB and hit F2. DFD will inform you that the data file MSPDEMO.DB does not exist and want's to know if you'd like DFD to create it for you. Answer DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 The Data File Debugger (DFD) Program - Advanced Section Page 4-7 Converting Data to Other Languages 'Y' (without quotes) and DFD will then ask how many Data Records you'd like the database file to have. Answer '5' (without quotes) and hit ENTER. DFD has just created an empty data file for you by the name of MSPDEMO.DB which we'll fill in a moment. The cursor should now be at the "Dict#:" prompt. ENTER a '1' (without quotes). The cursor will now move to the "Rec:" prompt. ENTER "/D" (without quotes) and DFD will respond with a "?". Overtype the "?" with "0+" (without quotes) and hit ENTER. DFD will now dump the entire database to the dump filename used when you started DFD (SAMPLE.DMP). When the dump process finishes dumping the last data record ("Rec: 4"), get the cursor back to the "Dict#:" prompt by hitting BACKTAB (Shift+Tab). ENTER '2' (without quotes) to tell DFD you now want to work with the MSPDEMO data dictionary and MSPDEMO.DB data file. The cursor will now be located at the "Rec:" prompt again. ENTER "/Z" (without quotes) and DFD will ask you which file to "zap" from. Respond with "SAMPLE.DMP" (without quotes) and hit ENTER. DFD will now "zap" the data file in the proper format with the data found in the "SAMPLE.DMP" file. When the "zap" process finsishes, the data file MSPDEMO.DB will now contain Microsoft Pascal readable and writable data! Let's take a look at what happened. First we created a source record file of the language we wanted to convert to. We made sure the variable names stayed the same, but changed the syntax to correspond to the language we want. Next we created a DAD for the new language record layout. Then we went into DFD and had DFD create an empty data file. We dumped the old data file to a dump file. Since dump files are written out in AOL (Assignment Oriented Language), this same dump file was used as input to the "zap" process to "zap" the newly created data file with the data we wanted. Although this process of dumping and zapping takes a lot of time to perform (and sufficient disk space to hold the dump), it sure beats manual data entry of perhaps thousands of elements and it removes the possibility of human error. Incidentally, note that the same data as stored by Turbo Pascal in the file DEMO.DB as compared to the Microsoft Pascal data stored in the file MSPDEMO.DB is smaller in size. This is due mainly because Microsoft Pascal aligns its data on word boundaries, whereas Turbo Pascal does not. Therefore, space gets wasted with Microsoft Pascal, however, Microsoft claims faster data access with their data scheme - you be the judge. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DAD Utility Programs Page 5-1 DAD Utility Programs - Overview DAD Utility Programs DAD Utility Programs are programs that manipulate or extract information from a DAD (Data Dictionary). There are four such programs that are included in the DFD package. These are: DADSORT - alphabetically sorts variables by name DAD2SRCE - converts a DAD to source code DADRPT - produces a report of a DAD in human-readable form DADUNIQ - scans a DAD for duplicate variable names and makes them unique. The DADSORT and DADUNIQ programs manipulate (change) the DAD, while the DAD2SRCE and DADRPT programs extract information from the DAD to produce human-readable text files. All DAD utility programs will give a brief description of the syntax by executing them at the DOS command prompt without providing parameters. For example, run DAD2SRCE without parameters for information on how to start the program and the different options available. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DAD Utility Programs Page 5-2 DADSORT DADSORT The DADSORT is a DAD utility program that sorts a Data Dictionary (DAD) in alphabetical order by variable name. The syntax for its use is: DADSORT dadfile where "dadfile" is the name of a data dictionary. Data dictionaries have filename extensions of ".DAD" and DADSORT knows this, so do not supply a filename extension as DADSORT will automatically look for the data dictionary with an extension of ".DAD". DADSORT sorts the DAD file in a certain way. After sorting, you will notice from the DFD program (when choosing a variable from this DAD) that RECORDs and REFERENCEs always appear at the top of the variable list. As usual, RECORDs are in magenta, and REFERENCEs are in green. The member names are then listed (in brown) in alphabetical order. Without sorting, all variables appear in the DFD selection list as they were found in your program which may be more comfortable for you. But if someone else is updating a database and there is a huge selection of variables, then it would be easier for them to use a sorted list of variables rather than looking through every screen for a particular variable name. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DAD Utility Programs Page 5-3 DAD2SRCE DAD2SRCE The DAD2SRCE utility program uses a data dictionary as its input, and the comments and tags files if available. It produces as output, a source code version of the dictionary (and comments and tags if available). If you're data dictionary name is TEST, then you would start DAD2SRCE with: DAD2SRCE TEST DAD2SRCE will look for "TEST.DAD" (data dictionary) first, and then "TEST.TAD" (tag dictionary), and then "TEST.KAD" (comment dictionary). As long as it finds "TEST.DAD" the program will run succesfully. If it finds the tag dictionary ("TEST.TAD"), it will include tags in the source code output. If it finds the comment dictionary ("TEST.KAD"), it will include comments in the source code output. The output from DAD2SRCE is automatically routed to your display screen. If you wish to have the output go to your printer, you must redirect the output of this program to the printer with the redirection symbol (">") as follows: DAD2SRCE TEST >PRN Likewise, if you want to have output go to a disk file, you can redirect the output of this program to a disk file: DAD2SRCE TEST >TEST.OUT DAD2SRCE also has different options available for different languages. These options add certain things to the generated source code. The options are specified by following the dictionary name with one or more spaces and the option. The options available are: /B - Generate bracketed offsets (MS-PASCAL only!) /C - Generate compilable code to print structure sizes (C only) /O - Generate Offset and record length info as comments /L=LANGUAGE - Generate code for a given language, where LANGUAGE is one of: C86 (Computer Innovations C) TC (Turbo C/MS C) MSPAS (Microsoft Pascal) TPAS (Turbo Pascal) Exercise care when using this option. To generate a source file from a Turbo Pascal dictionary named "test.dad" with offset and record length information as comments, and route the output to a file named "test.out", you would execute DAD2SRCE DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DAD Utility Programs Page 5-4 DAD2SRCE as follows: DAD2SRCE TEST /O >TEST.OUT To generate a Turbo C source file from a Turbo Pascal dictionary named "test.dad" with offset and record length information as comments, and route the output to a file named "test.out", you would execute DAD2SRCE as follows: DAD2SRCE TEST /O/L=TC >TEST.OUT The output file TEST.OUT will now contain generated source code, with information about record length and offsets as pertaining to each variable. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DAD Utility Programs Page 5-5 DADRPT DADRPT This utility program produces a report of a DAD (Data Dictionary). The report contains a human-readable version of what's in the DAD. For each variable, record, or reference, the report contains the following information: Variable Name X : Tag Number : Comment Number : Record Offset : Declaration : No. dimensions : Length : Record Number : Record Reference : Of course all fields to the right of each (":") will be filled in by DADRPT. In the first field "Variable Name X", X is replaced with the sequence number of the variable, that is the order in which that variable appeared when the dictionary was created. Note that this report will be in order by sequence number in an unsorted dictionary, and in alphabetical order by variable name in a sorted dictionary. To run DADRPT, simply enter DADRPT followed by the dictionary name at the DOS command prompt. For example, if your dictionary is TEST.DAD, you would start DADRPT as follows: DADRPT TEST Do not supply a filename extension, as DADRPT automatically looks for an extension of ".DAD". Note that the output of DADRPT goes to your display screen. So if you want the output to go to your printer, you would have to redirect the output to the printer with the ">" character as follows: DADRPT TEST >PRN Likewise, if you want the output to go to a file instead, you would redirect the output to that file as follows: DADRPT TEST >TEST.RPT DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DAD Utility Programs Page 5-6 DADUNIQ DADUNIQ This utility program may be necessary for you. While the Pascal compiler and some C compilers let you use the same member name inside different RECORDs or STRUCTs, DFD does not. Each variable name, whether it is a recordname, structname, membername, reference or anything else, must be unique. While the language scanners and DAD builder programs will go ahead and build the dictionary, DFD will not fetch the right variable if it appears more than once, as DFD only looks for the first match it finds. Therefore, DADUNIQ is a utility program that goes through your DAD and makes all duplicate variable names unique. It is a good idea to run the DADUNIQ program after every dictionary you create just to make sure that the variable names are unique. To run this utility, simply enter the following at the DOS command prompt: DADUNIQ DADNAME where DADNAME is the name of your data dictionary. Do not supply a filename extension, as DADUNIQ automatically searches for an extension of ".DAD". DADUNIQ makes variable names unique by appending invisible characters to the end of the name. For purposes of our example, let's suppose that the invisible character is the "&" character. So if your source code had 5 duplicate names such as "PHONE", the DADUNIQ program would rename these variables as follows: PHONE PHONE& PHONE&& PHONE&&& PHONE&&&& Note that the first occurence of PHONE was left unaltered. Also note that there is a 31-character maximum for a variable name. If your variable names are close to this limit, DADUNIQ may fail because it would append invisible characters to the name bringing it beyond this 31-character maximum. If this happens, DADUNIQ will issue an error message and quit. You must then edit the variable names in your text editor to fix the problem, and re-create the dictionaries. While listing the variable names in DFD, there will be no obvious difference in appearance of duplicate variable names to you. This is because the variable names are appended to with invisible characters by DADUNIQ, so you will not see any difference. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Demo - Walking Through the Demo Page A-1 Walking Through the Demo Since Turbo Pascal is so popular these days, we've decided to do a demo using that language. Please note that you do not need the Turbo Pascal compiler or any of the Turbo Pascal system to perform this demo. Make sure you've copied the distribution diskette to a subdirectory on your fixed disk. You should be in that subdirectory of your fixed disk while doing this demo. We've set up a source record layout in a file called DEMO.REC and the database described by this record layout is contained in a file called DEMO.DB (this is the data file or database file with all the data in it). If you copy the file DEMO.REC to your printer, you'll find that it looks like the copy of the file on the following page. Print a copy of this file out on your printer by entering the following on the DOS command prompt: COPY DEMO.REC PRN You will need it for the demo. DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Demo - Walking Through the Demo Page A-2 { Gilmore Systems demo source for a hypothetical car salesperson } { The following #START_SET and #END_SET defines tag names } {#START_SET} YEAR=1960..1987; CARPET_TYPE=1..4; LOCATION=1..2; PREFERENCE=1..2; {#END_SET} Optionrec = record air : string[3]; { Yes/No for Air Conditioning } stereo : string[3]; { Yes/No for Stereo Radio } powerstr : string[3]; { Yes/No for Power Steering } powerbrk : string[3]; { Yes/No for Power Brakes } powerwnd : string[3]; { Yes/No for Power Windows } carpeting : array[CARPET_TYPE] of string[3]; { Carpet} end; Carrec = record make : string[20]; { Manufacturer of car } qty_left : array[YEAR] of integer; { Year of car } model : string[20]; { Model name of car } options : Optionrec; { Options Information } color : string[10]; { Color of car } end; Namerec = record lastname : string[20]; { Customer's Last Name } firstname : string[20]; { Customer's First Name } middleInit : char; { Customer's Middle Initial } end; Addressrec = record street : string[20]; { Customer's Street Address } city : string[20]; { Customer's City } state : string[2]; { Customer's State } zip : string[10]; { Customer's Zip code } end; Phonerec = record area_code : string[3]; { Customer's area code } ph_number : string[10]; { Customer's phone number } end; PriceRec = record lowest : real; { Lowest price customer wants } highest : real; { Highest price customer wants } end; DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Demo - Walking Through the Demo Page A-3 Customer = record name : Namerec; { Customer Name info } address : Addressrec; { Customer Address info } phone : array[LOCATION] of Phonerec; { Phone } car : array[PREFERENCE] of Carrec; { Car } PriceRange : PriceRec; LastContact : string[9]; { Date last contacted } end; DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Demo - Walking Through the Demo Page A-4 After observing the record layout, you'll notice that there is no code in the file - purely RECORD descriptions. This is all DFD needs to know about. To make a DAD (Data Dictionary) out of this, it is a 2-step process. For the first step, you'll need to know the name of the main record. In this example, it is obviously "Customer", so enter the following at the DOS command prompt: PASSCAN DEMO.REC CUSTOMER PASSCAN starts the Pascal Scanner program. DEMO.REC tells the scanner program that this is the name of the source record layout file for it to scan, and CUSTOMER tells it that this is the name of the main record. PASSCAN will now scan the DEMO.REC file and build an intermediate file called DEMO.RRR which will be used as input to the DAD builder program. When PASSCAN finishes, you will invoke the DAD builder for Turbo Pascal with the following at the DOS command prompt: TPAS2DAD DEMO Note that no filename extension is supplied here since TPAS2DAD (Turbo Pascal to DAD) automatically looks for a file with the extension of ".RRR". If TPAS2DAD finds any errors, it will issue an error message with the line number of the line in question. This line number refers to the line in the ".RRR" (DEMO.RRR in this case) file in question. From there you can extrapolate the line in question in your main file. When TPAS2DAD finishes, it will have created the following three files: DEMO.DAD - The data dictionary DEMO.TAD - The tag dictionary DEMO.KAD - The comment dictionary and show you the size of each of the records in the file: record 1 "optionrec" = 36 bytes record 2 "carrec" = 145 bytes record 3 "namerec" = 43 bytes record 4 "addressrec" = 56 bytes record 5 "phonerec" = 15 bytes record 6 "pricerec" = 12 bytes record 0 "customer" = 441 bytes Record 0 is always the main record. The other records start with 1 and appear in the order they were encountered. Now you can go ahead and start the DFD program. Before you do, make sure your printer is online and ready to receive data since we will be using the printer later in this demo. To start the DFD program, simply enter the following at the DOS command prompt: DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Demo - Walking Through the Demo Page A-5 DFD In a few seconds, the DFD display screen will appear and will look similar to this: ┌───[ Data File Debugger (DFD) - (C)Copyright 1986, 1987 - Gilmore Systems ]───┐ │Dictionary01: Data: │ │Dictionary02: Data: │ │Dictionary03: Data: │ │Dictionary04: Data: │ │Dictionary05: Data: │ │Dictionary06: Data: │ │Dictionary07: Data: │ │Dictionary08: Data: │ │Dictionary09: Data: │ │Dictionary10: Data: │ │Dictionary11: Data: │ │Dictionary12: Data: │ │Dictionary13: Data: │ ├─[F1=Help F2=Continue F3=Swap F4=Clear F9=DOS F10=Quit]──────────────────┤ │Dict#: #Data Records: Rec: │ Tag ( ) Dimens ( ) Subsc│ │Varname: │1 │ │Rec( ) │2 │ │Ref( ) │3 │ │Type: Language: │4 │ │Length: Sequence Number: │5 │ │Main Offset: Record Offset: │6 │ ├────────────────────────────────[ D A T A ]────────────────────────────────┤ │ │ └───────────────────────────[ ]───────────────────────────┘ When this screen appears, the cursor will be located at the "Dictionary01:" prompt field. You are to enter the word "DEMO" here since this is the dictionary you are working with. Hit the ENTER key after typing "DEMO" and the cursor will now be located at the "Data:" prompt on the same line. Here you will respond with "DEMO.DB" and hit ENTER. The cursor will now move to the "Dictionary02:" prompt. You could enter up to 13 dictionaries and 13 database files, but for now we'll work with one. Note that if you want to go back to a previous field, hit the BACKTAB (Hold Shift will pressing TAB) key and the cursor will move to the previous field. After you've entered "demo" and "demo.db" as outlined above, hit the function key F2. DFD will now pause a couple of seconds to see if the entries are all valid. Once this is done, the cursor will be located at the "Dict#:" prompt. This is where you tell DFD which DAD (Data Dictionary) you want to work with. Since we only have one entered for now, choose 1 (for Dictionary01) and hit ENTER. DFD will now load dictionary #1 ("demo" in this case), print the number of data records the database file ("demo.db") has, and locate the cursor at the "Rec:" prompt. The "Rec:" prompt asks you which data record in the file you want to work with. There are 5 data records in the "demo.db" file, and so you DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Demo - Walking Through the Demo Page A-6 would choose a number from 0 to 4 (the first record is 0, the second is 1, ...the fifth is 4). Enter "0" (without quotes). After hitting ENTER, DFD takes you to a new screen listing the references and variable names in the main record. This screen is the variable selection screen. If you're using a color monitor, note that the record name is in magenta, references are in green, and member names of variables are in brown. DFD will not allow you to choose a RECORD since you're already there. Use the up and down cursor (arrow) keys to move about the variable selection. As you hit the down cursor key, note that the display highlights the variable name you're on (If no highlighting occurs, adjust your brightness and/or contrast knobs on the display until it does). Use the cursor keys to get the ADDRESS field highlighted. When this field is highlighted hit ENTER. Since ADDRESS is a REFERENCE to another RECORD, that other RECORD (ADDRESSREC) gets displayed. ADDRESSREC is a SUBRECORD of the CUSTOMER record. It's members (in brown) are listed below it. From looking at the source code, ADDRESSREC does not reference any other records in it, it simply has four members of STRING data types. Use the arrow keys to select the CITY variable and hit ENTER. The DFD display screen will now return with all the information fields filled in, and the D A T A field will contain the data it found for CUSTOMER[0].ADDRESSREC.CITY which will be "Boston" in this case. The cursor will be located under the first character of the string, or "B" in this case. You can now edit this data by simply typing over it. While you are editting data, a few other keys are available to you as follows: Esc - Blank out the data field Del - Delete character under cursor Ins - Toggle insert mode off/on Home - Move cursor to beginning of field End - Move cursor to end of field ENTER - Accept update (immediately updates database file) F2 - Same as ENTER F4 - cancels data entry for this variable BACKTAB (Shift+Tab) - same as F4 Change "Boston" to "Cambridge" and hit ENTER. The update is accepted and immediately performed and the cursor is located back at the "Dict#:" prompt. Since we still want to work with the same dictionary, (#1), simply hit ENTER. The cursor should now be located at the "Rec:" prompt. Enter "0" (without quotes) again to get the variable list on the screen. Select ADDRESS again and then select CITY again. DFD should now return with the contents of the database for this field with "Cambridge", this verifies that the change did indeed take place! Simply hit ENTER or F4 to get back to the "Dict#:" prompt. Keep using Dictionary01. Get the cursor back to the "Rec:" prompt again. Note that when the cursor is at the "Rec:" prompt, you could return back to the "Dict#:" DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Demo - Walking Through the Demo Page A-7 prompt by hitting BACKTAB (Shift+Tab). Get the cursor back to the "Rec:" prompt once again. Enter a 1 this time instead of 0. Go through the variable selection screens as above to choose ADDRESS and CITY again. The DFD screen should come back with "Detroit" this time since that's what it found in the database file's 2nd data record. Get the cursor back to the "Rec:" prompt one more time. Enter a 0 this time. Move the selection back to ADDRESS again and hit F1. Note that the bottom of the selection screen contains the comment found for this reference. You can modify the comment or simply hit ESC to get back to the selection process. Now move the selection to PHONE (PHONE will be highlighted when you get there). Select this field by hitting ENTER and note what happens! Looking at the source code, PHONE is a 1-dimensional variable whose subscript range is described by a tag called LOCATION (a tag is not a variable name, it is simply to help you remember what a subscript is used for). The customer in this record can have two phone numbers and DFD is asking which one you want. Type "1" (without quotes) and hit ENTER. DFD will now display the PHONEREC variables. Use the cursor keys to get PH NUMBER highlighted (Note DFD removes underscores to promote readibility) and select it by hitting ENTER. DFD will return to the main display screen again with the D A T A field filled in with "555-1234". Get the cursor back to the "Rec:" prompt once again. Enter a 3 this time (for the 4th data record). In the variable selection screen, select CAR (get the CAR field highlighted by using the down cursor key and hit ENTER). Note that CAR is a 1-dimensional array of type CARREC. ENTER a "1" (without quotes) and the CARREC subrecord will now be displayed. Note that on this screen, OPTIONS is in green (indicating that it is a REFERENCE to another record). Select the QTY LEFT field (get QTY LEFT highlighted by using the down cursor key and hit ENTER). DFD returns with the familiar main screen, but since QTY LEFT is a dimensioned variable, the "Tag" and "Dimens" fields are filled in and the cursor is awaiting a response to the subscript you want to work with. Enter 1980 (type 1980 and hit ENTER). DFD will now display the data found for CUSTOMER[3].CAR[1].QTY_LEFT[1980] which should be a "9" (The dealer has 9 of these 1980 model cars left). Now let's try dumping the database file to your printer. Make sure your printer is online and has plenty of paper. Get the cursor back to the "Rec:" prompt once again, only this time enter "/D" (without quotes) by typing a slash (/) and the letter D (D) and hit ENTER. DFD will come back with a "?". This is DFD's way of asking you which data record you want to dump. Respond by typing the digit "2" (without quotes) and hit ENTER. DFD will now dump this data record to the printer. If you wanted to dump the entire database to the printer you would respond to the "?" prompt with "0+" (without quotes) and hit ENTER. A dump of the entire database file for this demo database would be about 10 pages long. Feel free to play with all the variables you like and get comfortable with DFD. This has been a very small demonstration of DFD's DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 DFD Demo - Walking Through the Demo Page A-8 capabilities. Just enough to get you started with the basics which may be all you'll ever use. As you learn other commands and advanced features, you'll find DFD's use even more invaluable. If you happen to be using Turbo Pascal version 3.01, there is a sample program called CALC.PAS and a database file called CALCDEMO.MCS that is supplied on the Turbo System Diskette. If you'd like to play with the CALCDEMO.MCS database file in DFD, you can make a DAD out of it by entering the following source record layout with your text editor: CellRec = Record CellStatus : byte; Contents : string[70]; Value : real; DEC : byte; FW : byte; end; If you compare this with the original source code definition of the file, be sure to note how all data declarations have been reduced to simple scalar data types. Save the above layout into a filename, say CALC.REC and start the scanner: PASSCAN CALC.REC CELLREC Next, create the DAD: TPAS2DAD CALC The next time you use DFD, supply CALC as a dictionary name and CALCDEMO.MCS as the data file name and you're in business! DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Index Page B-1 - " - "?" ................. 3-6, 4-1, 4-2, 4-7, A-7 - * - *** data record ..... 4-5 - / - /d .................. 3-6, 4-1, 4-2, 4-7, A-7 /f .................. 4-1, 4-2 /i .................. 4-1, 4-2 /m .................. 4-1, 4-2 /z .................. 3-6, 4-3, 4-7 - 3 - 31-character limit .. 2-11, 2-24 - A - Align ............... 2-10 - B - Brown ............... 3-6, A-6 - C - Case ................ 1-1, 1-2, 2-2, 2-3, 2-4, 2-10, 2-12, 2-17, 2-18, 3-1, 3-4, 3-9, A-6 Color ............... 1-3, 3-6, A-2, A-6 Comments ............ 1-2, 2-3, 2-6, 2-13, 2-16, 2-19, 5-3, 5-4 - D - Dad builder ......... 2-1, 2-6, 2-10, 2-13, 2-14, 2-19, 2-23, 3-1, A-4 Data types .......... 1-4, 2-3, 2-4, 2-5, 2-12, A-6, A-8 Declaration ......... 2-16, 5-5 Delimiters .......... 2-13, 4-4 Descriptive names ... 2-20 Directives .......... 2-6, 2-7, 2-8, 2-20, 2-21 Duplicate ........... 1-4, 2-11, 2-24, 5-1, 5-6 - E - Edit ................ 2-2, 2-14, 4-3, 4-5, 4-6, 5-6, A-6 - F - Fixed length ........ 2-16 DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Index Page B-2 - G - Green ............... 3-6, 5-2, A-6, A-7 - H - Header .............. 3-4 - I - Ieee ................ 1-1 Invisible characters 2-11, 2-24, 5-6 - L - Lstring ............. 2-3, 2-12, 3-9 - M - Magenta ............. 3-6, 5-2, A-6 Member .............. 1-4, 2-11, 2-24, 3-6, 3-7, 5-2, 5-6, A-6 - N - Nested .............. 1-1, 1-2, 2-3, 2-6, 2-16, 2-19 Null ................ 2-15, 2-16, 3-3 Null-terminated ..... 2-15 - O - Offset .............. 2-13, 3-4, 5-3, 5-4, 5-5 Offsets ............. 1-1, 2-1, 2-13, 5-3, 5-4 - P - Protection .......... 2-6, 2-19 - R - Random .............. 1-1, 2-1, 3-4 Random files ........ 1-1 Reals ............... 3-9 Record .............. 1-1, 1-2, 2-1, 2-2, 2-3, 2-4, 2-7, 2-8, 2-9, 2-10, 2-12, 2-15, 2-16, 2-17, 3-2, 3-4, 3-6, 4-2, 4-4, 4-5, 4-6, 4-7, 5-3, 5-4, 5-5, A-1, A-2, A-3, A-4, A-5, A-6, A-7, A-8 Record layout ....... 1-1, 2-1, 4-6, A-1, A-4, A-8 Redirect ............ 5-3, 5-5 Reference ........... 2-3, 2-4, 2-15, 2-16, 3-6, 5-5, 5-6, A-6, A-7 - S - Scalar .............. 2-2, 2-4, 2-6, 2-12, 2-14, 2-19, A-8 Scanner ............. 1-4, 2-1, 2-2, 2-3, 2-4, 2-6, 2-8, 2-9, 2-14, DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988 Index Page B-3 2-16, 2-19, 2-21, 2-22, 4-6, A-4 Set ................. 2-7, 2-8, 2-14, 2-20, 2-21, A-1 Source .............. 1-1, 1-4, 2-1, 2-2, 2-7, 2-9, 2-13, 2-14, 2-17, 2-20, 2-22, 3-6, 4-2, 4-6, 4-7, 5-1, 5-3, 5-4, 5-6, A-1, A-2, A-4, A-6, A-7, A-8 Strings ............. 1-1, 2-12, 2-15, 2-20, 4-4, 4-6 Struct .............. 1-1, 1-2, 2-1, 2-14, 2-15, 2-16, 2-17, 2-18, 2-20, 2-21, 2-22, 2-23 Struct { ............ 2-16, 2-17, 2-18, 2-23 Subscript ........... 2-3, 2-7, 2-8, 2-16, 2-21, 4-1, 4-2, A-7 Syntax .............. 2-1, 2-2, 2-3, 2-4, 2-9, 2-16, 2-18, 2-22, 4-7, 5-1, 5-2 - T - Tag ................. 1-1, 2-1, 2-3, 2-7, 2-8, 2-9, 2-20, 2-21, 2-22, 3-2, 4-2, 5-3, 5-5, A-2, A-4, A-5, A-7 - U - Union ............... 1-2, 2-14, 2-16, 2-17, 2-18, 2-23 Union { ............. 2-16, 2-17, 2-18, 2-23 Unique .............. 1-1, 1-4, 2-11, 2-24, 5-1, 5-6 - V - Variant ............. 2-2, 2-14, 2-17, 2-18 - Z - Zstring ............. 2-14, 2-15, 2-20, 2-21, 2-22 DFD User Guide - (C)Copyright Gilmore Systems - 1986, 1987, 1988